Checks if a keyboard key or mouse/joystick button is down or up. Also retrieves joystick status.
GetKeyState, OutputVar, KeyName [, Mode]
KeyIsDown := GetKeyState("KeyName" [, "Mode"])
| OutputVar | The name of the variable in which to store the retrieved key state, which is either D for down or U for up (but the GetKeyState() function returns true (1) for down and false (0) for up). The variable will be empty (blank) if the state of the key could not be determined. The items below apply only to joysticks: 1) For a joystick axis such as JoyX, OutputVar will be set to a floating point number between 0 and 100 to indicate the joystick's position as a percentage of that axis's range of motion. The format of the number can be changed via SetFormat. This test script can be used to analyze your joystick(s). 2) When KeyName is JoyPOV, the retrieved value will be between 0 and 35900. The following approximate POV values are used by many joysticks: |
| KeyName | This can be just about any single character from the keyboard or one of the key names from the key list, such as a mouse/joystick button (though mouse button state usually cannot be detected on Windows 95/98/Me). Examples: B, 5, LWin, RControl, Alt, Enter, Escape, LButton, MButton, Joy1. Alternatively, an explicit virtual key code such as vkFF may be specified. This is useful in the rare case where a key has no name. The virtual key code of such a key can be determined by following the steps at the bottom fo the key list page. |
| Mode | This parameter is ignored when retrieving joystick status. If omitted, the mode will default to that which retrieves the logical state of the key. This is the state that the OS and the active window believe the key to be in, but is not necessarily the same as the physical state. Alternatively, one of these letters may be specified: P: Retrieve the physical state (i.e. whether the user is physically holding it down). Under Windows Me/98/95, the physical state (Mode = P) of a key is likely always the same as its logical state. Under Windows NT/2000/XP and beyond, the physical state of a key or mouse button will usually be the same as the logical state unless the keyboard and/or mouse hooks are installed, in which case it will accurately reflect whether or not the user is physically holding down the key or button (as long as it was pressed down while the script was running). You can determine if your script is using the hooks via the KeyHistory command or menu item. You can force the hooks to be installed by adding the #InstallKeybdHook and/or #InstallMouseHook directives to the script. T: Retrieve the toggle state (only valid for keys that can be toggled such as Capslock, Numlock, Scrolllock, and Insert). A retrieved value of D means the key is "on", while U means it's "off" (but the GetKeyState() function returns true (1) for "on" and false (0) for "off"). Retrieving the toggle state of the Insert key might work only on Windows 2000/XP or later. On Windows 9x, retrieving the toggle state might be less reliable. For example, immediately after the key is pressed, its new state might not be retrieved correctly until after the display of a window that's associated with the script, such as a MsgBox. |
To wait for a key or mouse/joystick button to achieve a new state, it is usually easier to use KeyWait instead of a GetKeyState loop.
Systems with unusual keyboard drivers might be slow to update the state of their keys, especially the toggle-state of keys like Capslock. A script that checks the state of such a key immediately after it changed may use Sleep beforehand to give the system time to update the key state.
For examples of using GetKeyState with a joystick, see the joystick remapping page and the Joystick-To-Mouse script.
GetKeyState(), KeyWait, Key List, Joystick remapping, KeyHistory, #InstallKeybdHook, #InstallMouseHook
; Basic examples: GetKeyState, state, RButton ; Right mouse button. GetKeyState, state, Joy2 ; The second button of the first joystick. GetKeyState, state, Shift if state = D MsgBox At least one Shift key is down. else MsgBox Neither Shift key is down. GetKeyState, state, CapsLock, T ; D if CapsLock is ON or U otherwise. state := GetKeyState("Capslock", "T") ; True if CapsLock is ON, false otherwise. ; Remapping example (this is only for illustration because it would be easier to use ; the built-in remapping feature): ; In the following hotkey, the mouse button is kept held down while NumpadAdd is ; down, which effectively transforms NumpadAdd into a mouse button. This method ; can also be used to repeat an action while the user is holding down a key or button: *NumpadAdd:: MouseClick, left,,, 1, 0, D ; Hold down the left mouse button. Loop { Sleep, 10 GetKeyState, state, NumpadAdd, P if state = U ; The key has been released, so break out of the loop. break ; ... insert here any other actions you want repeated. } MouseClick, left,,, 1, 0, U ; Release the mouse button. return ; Example: Make joystick button behavior depend on joystick axis position. joy2:: GetKeyState, joyx, JoyX if joyx > 75 MsgBox Action #1 (button pressed while joystick was pushed to the right). else if joyx < 25 MsgBox Action #2 (button pressed while joystick was pushed to the left). else MsgBox Action #3 (button pressed while joystick was centered horizontally). return ; See the joystick remapping page and the Joystick-To-Mouse script for other examples.